Gathers color information about a single pixel map or bitmap.

OSErr GetPixMapInfo (
    PixMapHandle thePixMapHandle, 
    PictInfo *thePictInfo, 
    SInt16 verb, 
    SInt16 colorsRequested, 
    SInt16 colorPickMethod, 
    SInt16 version
);

Parameter descriptions

thePixMapHandle

A handle to a pixel map or bitmap.

thePictInfo

On return, a pointer to a PictInfo structure, which holds information about a pixel map or bitmap. Initially, all of the fields in a new PictInfo structure are set to NULL. Relevant fields are set to appropriate values depending on the information you request using the GetPixMapInfo function.

This function also collects information from black-and-white pictures and bitmaps, and is supported in System 7 even by computers running only basic QuickDraw. However, when collecting color information on a computer running only basic QuickDraw, this function returns NULL instead of a handle to a Palette or ColorTable structure.

verb

A value indicating whether you want color information returned in a ColorTable structure, a Palette structure, or both. You can also request that black and white not be included among the returned colors. See “Verb Constants” for a description of the values you can use here.

Because the Palette Manager adds black and white when creating a Palette structure, you can specify the number of colors you want minus 2 in the colorsRequested parameter and specify the constant suppressBlackAndWhite in the verb parameter when gathering colors destined for a Palette structure or a screen.

colorsRequested

From 1 to 256, the number of colors you want in the ColorTable or Palette structure returned via the PictInfo structure.

colorPickMethod

The method by which colors are selected for the ColorTable or Palette structure returned via the PictInfo structure. See “Color Selection Method Constants” for a description of the values you can use here.

You can also create your own color-picking method in a resource file of type 'cpmt' and pass its resource ID in the colorPickMethod parameter. The resource ID must be greater than 127.

version

Always set this parameter to 0.

function result

A result code.

DISCUSSION

The Picture Utilities provide two color-picking methods: one that gives you the most frequently used colors and one that gives you the widest range of colors. If you specify the systemMethod constant, the Picture Utilities choose that method. Currently they always choose popularMethod. You can also supply a color-picking method of your own.

When you are finished with the information in the PictInfo structure, be sure to dispose of it. Use the Memory Manager function DisposeHandle to dispose of the PictInfo structure. Dispose of the Palette structure by using the DisposePalette function. Dispose of the ColorTable structure by using the DisposeCTable function.

SPECIAL CONSIDERATIONS

The GetPixMapInfo function may move or purge memory.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)